SpineWise – Directory Structure (Code Submission)
==================================================

This README.txt documents the expected on-disk directory layout for the SpineWise project
(as shown in the provided directory screenshot). The exact layout can vary by project,
but this structure is complete for: (1) program source code, (2) deployable/runtime files,
and (3) supporting assets and trained models.

Root Directory
--------------
SpineWise/
│
├─ assets/                       Static assets (images/icons/sounds used by the app UI)
│  ├─ icons/                     App/GUI icon files (e.g., logo, GitHub/LinkedIn icons)
│  ├─ start_icon.png             UI button icon (example)
│  ├─ stop_icon.png              UI button icon (example)
│  ├─ calibrate_icon.png         UI button icon (example)
│  └─ (other .png/.jpg/.wav)     Any additional media required by the GUI
│
├─ models/                       Trained models and model artifacts used at runtime
│  ├─ posture_lgbm_classifier.pkl  LightGBM posture classifier bundle (ML engine)
│  └─ (other model files)          e.g., Mediapipe task models, additional .pkl/.onnx, etc.
│
├─ backend.py                    Core posture analysis logic (feature extraction, scoring, alerts, logging hooks)
├─ spinewise_gui.py              Main PyQt5 desktop GUI application (Dashboard/Analytics/Recommendations/Settings/About)
├─ spinewise_theme.py            Centralized UI theme (colors, QSS styles, helper style functions)
├─ voice_config.py               Voice command configuration (loads/saves voice_settings.json)
│
├─ log.py                        Windowed feature logger + dataset writer (posture_dataset.csv) and ML scoring integration
├─ ml_engine.py                  ML inference / decision logic helpers (model-loading, scoring, etc.)
├─ posture_image_logger.py       Helper for saving labeled posture images to posture_images/{good,bad,moderate}/
│
├─ train.py                      Training entrypoint / training utilities (project-specific; may vary)
├─ new_train_classifier.py        Classifier training pipeline (creates/updates models/posture_lgbm_classifier.pkl)
├─ upload_to_kaggle.py           Utility script to upload datasets/models to Kaggle (project-specific)
│
├─ frontend.py                   Lightweight entrypoint/launcher (if used by your project configuration)
├─ requirements.txt              Python dependency pin list for reproducible environment setup
└─ kaggle.json                   Kaggle API credentials (should NOT be committed to public repos)

Generated / Runtime Artifacts (Created When Running)
---------------------------------------------------
These files/folders are typically created automatically when you run the app locally:

SpineWise/
├─ posture_trend_log.csv         Trend log used by Analytics charts (generated by runtime logging)
├─ stats.json                    Analytics state (e.g., day counters / streak metadata)
├─ posture_dataset.csv           Labeled training dataset (generated by log.py when collecting samples)
├─ voice_settings.json           Persisted voice configuration (created/updated via voice_config.py)
├─ .spinewise_state.json         Local state (e.g., persistent user_id used for dataset grouping)
└─ posture_images/               Optional image dataset for labeling / model training
   ├─ good/
   ├─ moderate/
   └─ bad/

Notes
-----
1) “assets/” and “models/” are expected at the project root (peer folders of the .py files).
2) “kaggle.json” contains a private API key. Include it only in secure submissions; exclude it from public source control.
3) Exact filenames in assets/models may differ, but all application-required media and model artifacts should live
   under those folders so the project can be run from a clean checkout.
